home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / libdl / dlsym.z / dlsym
Encoding:
Text File  |  1998-10-30  |  5.9 KB  |  133 lines
  1.  
  2.  
  3.  
  4. DDDDLLLLSSSSYYYYMMMM((((3333CCCC))))                                                            DDDDLLLLSSSSYYYYMMMM((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ddddllllssssyyyymmmm - get the address of a symbol in shared object
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      cccccccc [ffffllllaaaagggg ...] ffffiiiilllleeee ...  ----llllcccc [lllliiiibbbbrrrraaaarrrryyyy ...]
  13.  
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddllllffffccccnnnn....hhhh>>>>
  15.  
  16.      vvvvooooiiiidddd ****ddddllllssssyyyymmmm((((vvvvooooiiiidddd ****hhhhaaaannnnddddlllleeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee))));;;;
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      ddddllllssssyyyymmmm allows a process to obtain the address of a symbol defined within a
  20.      shared object previously opened by ddddllllooooppppeeeennnn, ssssggggiiiiddddllllooooppppeeeennnn____vvvveeeerrrrssssiiiioooonnnn, or
  21.      ssssggggiiiiddddllllaaaadddddddd.  _h_a_n_d_l_e is a value returned by a call to ddddllllooooppppeeeennnn; the
  22.      corresponding shared object must not have been closed using ddddllllcccclllloooosssseeee.
  23.      _n_a_m_e is the symbol's name as a character string.  ddddllllssssyyyymmmm searchs for the
  24.      named symbol in all shared objects loaded automatically as a result of
  25.      loading the object referenced by _h_a_n_d_l_e [see ddddllllooooppppeeeennnn(3)].
  26.  
  27.      The name search is done in the following order:
  28.          If the _h_a_n_d_l_e is NULL, the base object is searched and then the rld-
  29.          list of objects is searched, looking only at globally-visible DSOs.
  30.  
  31.          If the _h_a_n_d_l_e is not NULL, the named object is searched and then the
  32.          library list of the DSO opened on _h_a_n_d_l_e is searched (in a pre-order
  33.          breadth-first search of all listed DSOs).
  34.  
  35.          The first visible symbol with the requested name (weak or strong) is
  36.          returned.
  37.  
  38.      For information on how names are generally resolved (as distinct from
  39.      _d_l_s_y_m resolution) and on symbol visibility see the ddddllllooooppppeeeennnn "NAMESPACE
  40.      ISSUES" section.
  41.  
  42.      Note that name resolution for names on the NULL _h_a_n_d_l_e is in rld-list
  43.      order whereas for other _h_a_n_d_l_es the resolution is in library-list order.
  44.  
  45. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  46.      The following example shows how one can use ddddllllooooppppeeeennnn and ddddllllssssyyyymmmm to access
  47.      either function or data objects.  For simplicity, error checking has been
  48.      omitted.
  49.  
  50.           void *handle;
  51.           int i, *iptr;
  52.           int (*fptr)(int);
  53.  
  54.           /* open the needed object */
  55.           handle = dlopen("/usr/mydir/libx.so", RTLD_LAZY);
  56.  
  57.           /* find address of function and data objects */
  58.           fptr = (int (*)(int))dlsym(handle, "some_function");
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDLLLLSSSSYYYYMMMM((((3333CCCC))))                                                            DDDDLLLLSSSSYYYYMMMM((((3333CCCC))))
  71.  
  72.  
  73.  
  74.           iptr = (int *)dlsym(handle, "int_object");
  75.  
  76.           /* invoke function, passing value of integer as a parameter */
  77.  
  78.           i = (*fptr)(*iptr);
  79.  
  80. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  81.      ddddlllleeeerrrrrrrroooorrrr(3), ddddllllooooppppeeeennnn(3), ssssggggiiiiddddllllooooppppeeeennnn____vvvveeeerrrrssssiiiioooonnnn(3), ddddllllcccclllloooosssseeee(3),
  82.      ssssggggiiiiggggeeeettttddddssssoooovvvveeeerrrrssssiiiioooonnnn(3), ssssggggiiiiddddllllaaaadddddddd(3).
  83.  
  84. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  85.      The C or C++ compiler may emit a warning similar to "warning(1048): cast
  86.      between pointer-to-object and pointer-to-function" when casting the
  87.      return type of ddddllllssssyyyymmmm to be a function pointer.  While a cast from
  88.      pointer-to-data to pointer-to-function is not necessarily portable to all
  89.      systems (which is what the warning means) the cast and the resulting call
  90.      will work fine on any system actually supporting ddddllllssssyyyymmmm.  One could define
  91.      a function
  92.      int (*dlsymfunc(void *handle,char *name))();
  93.      int (*dlsymfunc(void *handle,char *name))()
  94.      {
  95.              return (int (*)())dlsym(handle,name);
  96.      }
  97.      and call it instead of ddddllllssssyyyymmmm when getting function addresses: that has
  98.      the effect of moving the warning message to a single spot in the program
  99.      (the dlsymfunc definition) so the rest of the code does not get this
  100.      warning.
  101.  
  102.      If _h_a_n_d_l_e does not refer to a valid object opened by ddddllllooooppppeeeennnn, or if the
  103.      named symbol cannot be found within any of the objects associated with
  104.      _h_a_n_d_l_e, ddddllllssssyyyymmmm returns NNNNUUUULLLLLLLL. More detailed diagnostic information is
  105.      available through ddddlllleeeerrrrrrrroooorrrr.
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.